home *** CD-ROM | disk | FTP | other *** search
/ Aminet 21 / Aminet 21 (1997)(GTI - Schatztruhe)[!][Oct 1997].iso / Aminet / dev / misc / Prog_Bar_103.lha / prog_bar / Docs / prog_bar.doc < prev    next >
Encoding:
Text File  |  1997-07-15  |  14.9 KB  |  457 lines
  1. Prog_Bar v1.03 Function List
  2. ============================
  3.  
  4.     CreateProgBarA()
  5.     CreateProgBar()
  6.     SetProgBarAttrsA()
  7.     SetProgBarAttrs()
  8.     FreeProgBar()
  9.     RefreshProgBar()
  10.     UpdateProgBar()
  11.     ResetProgBar()
  12.     ClearProgBar()
  13.     ClearBar()
  14.     ClearText()
  15.  
  16.  
  17.  
  18. CreateProgBarA() / CreateProgBar()
  19. ----------------------------------
  20.  
  21. NAME
  22.         CreateProgBarA -- Allocates and initialises a progress bar.  (V1.00)
  23.         CreateProgBar -- Varargs stub for CreateProgBarA().  (V1.00)
  24.  
  25. SYNOPSIS
  26.         bar = CreateProgBarA ( Wnd, Left, Top, Width, Height, Size,
  27.                                taglist )
  28.  
  29.         PBAR *CreateProgBarA ( struct Window *, UWORD, UWORD, UWORD, UWORD,
  30.                                UWORD, struct TagList * )
  31.  
  32.         bar = CreateProgBar ( Wnd, Left, Top, Width, Height, Size,
  33.                               First_Tag, ... )
  34.  
  35.         PBAR *CreateProgBar ( struct Window *, UWORD, UWORD, UWORD, UWORD,
  36.                               UWORD, Tag, ... )
  37.  
  38. FUNCTION
  39.         Allocates  a  new  PBAR  structure,  initialises  it  to the default
  40.         values,  or  any  values  specified  in  the function call, and then
  41.         renders the progress bar to the specified window.
  42.  
  43. INPUTS
  44.         Wnd     - A pointer to the window in which the progress bar is to be
  45.                   rendered.   This may be NULL in which case no progress bar
  46.                   will be created.
  47.         Left    - The X position of the progress bar.
  48.         Top     - The Y position of the progress bar.
  49.         Width   - The Width of the progress bar.
  50.         Height  - The Height of the progress bar.
  51.         Size    - The  logical  size of the progress bar.  This is the value
  52.                   represented  by  the full bar.  It is not connected to the
  53.                   visual  dimensions of the progress bar.  If you try to set
  54.                   this value to zero you will actually get a bar with a size
  55.                   of one.
  56.         taglist - A   pointer  to  an  array  of  tags  specifying  optional
  57.                   parameters which will modify the behaviour of the progress
  58.                   bar.  If the default values are all that are required this
  59.                   can  be  NULL.  See SetProgBarAttrs() for more information
  60.                   about the various tags available.
  61.  
  62. RESULT
  63.         bar - If successful these functions will return a pointer to the new
  64.               progress  bar.   This  pointer  should  be  kept as it will be
  65.               needed  to  identify  the  progress  bar  for  all  the  other
  66.               functions.   These  functions  will only fail due to a lack of
  67.               memory, or the use of a NULL window pointer, in which case the
  68.               returned value will be NULL.
  69.  
  70. BUGS
  71.         None known
  72.  
  73. SEE ALSO
  74.         SetProgBarAttrs() FreeProgBar() RefreshProgBar() UpdateProgBar()
  75.  
  76.  
  77.  
  78. SetProgBarAttrsA() / SetProgBarAttrs()
  79. --------------------------------------
  80.  
  81. NAME
  82.         SetProgBarAttrsA -- Changes  the  behaviour  or  appearance  of  the
  83.                             progress bar.  (V1.00)
  84.         SetProgBarAttrs -- Varargs stub for SetProgBarAttrs().  (V1.00)
  85.  
  86. SYNOPSIS
  87.         SetProgBarAttrsA ( PBar, taglist )      ( A0, A1 )
  88.  
  89.         void SetProgBarAttrsA ( PBAR *, struct TagList * )
  90.  
  91.         SetProgBarAttrs ( PBar, First_Tag, ... )
  92.  
  93.         void SetProgBarAttrs ( PBAR *, Tag, ... )
  94.  
  95. FUNCTION
  96.         Changes  the  behaviour  or  appearance  of  a  progress bar to that
  97.         specified  by  the optional tags.  It will perform all the necessary
  98.         calculations and redraw the display.
  99.  
  100. INPUTS
  101.         PBar    - A  pointer to the progress bar to be altered.  This is the
  102.                   pointer returned by CreateProgBar().
  103.         taglist - A  pointer  to  a  tag  list.   The  available tags are as
  104.                   follows.
  105.  
  106.             PB_LeftEdge          The X position of the progress bar.
  107.             PB_TopEdge           The Y position of the progress bar.
  108.             PB_Width             The Width of the progress bar.  If you just
  109.                                  want a counter, you can set this to zero.
  110.             PB_Height            The  Height  of  the  progress bar.  If you
  111.                                  just  want  a  counter, you can set this to
  112.                                  zero.
  113.             PB_Direction         The  Direction  in  which  the progress bar
  114.                                  will grow.  Available options are
  115.                   PBDE_RIGHT     From Left to Right  ( default ).
  116.                   PBDE_LEFT      From Right to Left.
  117.                   PBDE_UP        From Bottom to Top.
  118.                   PBDE_DOWN      From Top to Bottom.
  119.                                  Any other value will be ignored.
  120.             PB_BarColour         The  pen  number  of  the  bar's foreground
  121.                                  colour.  The default value is 3 (Blue).
  122.             PB_BarBackColour     The  Pen  number  of  the  bar's background
  123.                                  colour.  The default value is 0 (Grey).
  124.             PB_BarSize           The  logical  size of the progress bar.  If
  125.                                  you  try to set this value to zero you will
  126.                                  actually get a bar with a size of one.
  127.             PB_BarValue          The  current Value of the progress bar.  It
  128.                                  is better to use UpdateProgBar()  to change
  129.                                  this  value  if  this  is  the only change.
  130.                                  However,  the  option  has been supplied so
  131.                                  that  the  value can be altered at the same
  132.                                  time  as  other  changes  are made.  If the
  133.                                  value  supplied  is greater than PB_BarSize
  134.                                  the actual value stored will be PB_BarSize.
  135.                                  This   guarantees   that   the  bar  cannot
  136.                                  overflow.
  137.             PB_BorderType        The   type   of  border  drawn  around  the
  138.                                  progress bar.  The available options are
  139.                   PBBT_NONE      No Border.
  140.                   PBBT_PLAIN     Plain Black Box  ( default ).
  141.                   PBBT_RECESSED  Recessed Box.
  142.                   PBBT_RAISED    Raised Box.
  143.                   PBBT_RIDGE     Raised Ridge.
  144.                                  Any other value will be ignored.
  145.             PB_TextMode          The  mode used for rendering the text.  The
  146.                                  available options are
  147.                   PBTM_NONE      No Text  ( default ).
  148.                   PBTM_PERCENT   Display Value as a percentage, e.g. 50%.
  149.                   PBTM_VALUE     Display Value as "Value/Size", e.g. 67/153.
  150.                                  Any other value will be ignored.
  151.             PB_TextPosition      The  position  you  want  the  text  to  be
  152.                                  displayed.  The available options are
  153.                   PBTP_BELOW     Text centred below the bar  ( default ).
  154.                   PBTP_ABOVE     Text centred above the bar.
  155.                   PBTP_LEFT      Text to the left of the bar.
  156.                   PBTP_RIGHT     Text to the right of the bar.
  157.                   PBTP_CENTRE    Text  centred  inside the bar.  If the text
  158.                                  will  not  fit  within  the  borders of the
  159.                                  progress bar, it will not be displayed.
  160.                                  Any other value will be ignored.
  161.             PB_TextColour        The  pen  number  of  the text's foreground
  162.                                  colour.  The default is 1 (Black).
  163.             PB_TextBackColour    The  pen  number  of  the text's background
  164.                                  colour.   The  default  is  0 (Grey).  This
  165.                                  value  is  ignored  if the text  is centred
  166.                                  within   the   bar.    In   this  case  the
  167.                                  background will be the bar itself.
  168.             PB_TextFont          A  pointer to a TextAttr structure defining
  169.                                  the  font to be used for the text.  If this
  170.                                  value  is  NULL  the  window's font will be
  171.                                  used (default).
  172.  
  173. NOTES
  174.         If  the  supplied PBAR pointer is NULL this function will do nothing
  175.         and return immediately.
  176.  
  177. RESULT
  178.         None
  179.  
  180. BUGS
  181.         None known
  182.  
  183. SEE ALSO
  184.         CreateProgBar() FreeProgBar()
  185.  
  186.  
  187.  
  188. FreeProgBar()
  189. -------------
  190.  
  191. NAME
  192.         FreeProgBar -- Deletes  a  progress bar from the screen and releases
  193.                        all memory used by it.  (V1.00)
  194.  
  195. SYNOPSIS
  196.         FreeProgBar ( PBar )     ( A0 )
  197.  
  198.         void FreeProgBar ( PBAR * )
  199.  
  200. FUNCTION
  201.         Releases all the memory used by the progress bar and removes it from
  202.         the screen.
  203.  
  204. INPUTS
  205.         PBar - A  pointer  to  the  progress  bar  to be freed.  This is the
  206.                pointer   returned   by   CreateProgBar().    After   calling
  207.                FreeProgBar() you should not use PBar again.
  208.  
  209. NOTES
  210.         If  the  supplied PBAR pointer is NULL this function will do nothing
  211.         and return immediately.
  212.  
  213. RESULT
  214.         None
  215.  
  216. BUGS
  217.         None known
  218.  
  219. SEE ALSO
  220.         CreateProgBar() SetProgBarAttrs() ClearProgBar()
  221.  
  222.  
  223.  
  224. RefreshProgBar()
  225. ----------------
  226.  
  227. NAME
  228.         RefreshProgBar -- Redraws a progress bar.  (V1.00)
  229.  
  230. SYNOPSIS
  231.         RefreshProgBar ( PBar )     ( A0 )
  232.  
  233.         void RefreshProgBar ( PBAR * )
  234.  
  235. FUNCTION
  236.         Redraws   a  progress  bar  in  its  current  state.   It  does  not
  237.         recalculate any of the progress bar's internal values.
  238.  
  239. INPUTS
  240.         PBar - A  pointer  to  the  progress bar to be redrawn.  This is the
  241.                pointer returned by CreateProgBar().
  242.  
  243. NOTES
  244.         If  the  supplied PBAR pointer is NULL this function will do nothing
  245.         and return immediately.
  246.  
  247. RESULT
  248.         None
  249.  
  250. BUGS
  251.         None known
  252.  
  253. SEE ALSO
  254.         CreateProgBar() SetProgBarAttrs() FreeProgBar() UpdateProgBar()
  255.         ResetProgBar()
  256.  
  257.  
  258.  
  259. UpdateProgBar()
  260. ---------------
  261.  
  262. NAME
  263.         UpdateProgBar -- Change  the  current  value  of  a progress bar and
  264.                          redisplay its imagery.  (V1.00)
  265.  
  266. SYNOPSIS
  267.         UpdateProgBar ( PBar, Value )     ( A0, D0 )
  268.  
  269.         void UpdateProgBar ( PBAR *, UWORD )
  270.  
  271. FUNCTION
  272.         Updates  the  current  value  of  the progress bar, performs all the
  273.         necessary recalculations and redisplays the progress bar.
  274.  
  275. INPUTS
  276.         PBar  - A  pointer to the progress bar whose value is to be changed.
  277.                 This is the pointer returned by CreateProgBar().
  278.         Value - The new value for the progress bar.
  279.  
  280. NOTES
  281.         If  the  supplied PBAR pointer is NULL this function will do nothing
  282.         and return immediately.
  283.  
  284.         If  the  value  supplied  is  greater  than  the  size  of  the  bar
  285.         (PB_BarSize)  the  actual  value  stored  will  be PB_BarSize.  This
  286.         guarantees that the bar cannot overflow.
  287.  
  288.         If  the  bar's  value  is  to  be  changed at the same time as other
  289.         properties it is better to use SetProgBarAttrs().
  290.  
  291. RESULT
  292.         None
  293.  
  294. BUGS
  295.         None known
  296.  
  297. SEE ALSO
  298.         CreateProgBar() SetProgBarAttrs() FreeProgBar() RefreshProgBar()
  299.         ResetProgBar()
  300.  
  301.  
  302.  
  303. ResetProgBar()
  304. --------------
  305.  
  306. NAME
  307.         ResetProgBar -- Reset  the  current  value of a progress bar to zero
  308.                         and redisplay its imagery.  (V1.00)
  309.  
  310. SYNOPSIS
  311.         ResetProgBar ( PBar )    ( A0 )
  312.  
  313.         void ResetProgBar ( PBAR * )
  314.  
  315. FUNCTION
  316.         Resets  the  current value of the progress bar to zero, performs all
  317.         the necessary recalculations and redisplays the progress bar.
  318.  
  319. INPUTS
  320.         PBar - A  pointer  to  the  progress bar whose value is to be reset.
  321.                This is the pointer returned by CreateProgBar().
  322.  
  323. NOTES
  324.         If  the  supplied PBAR pointer is NULL this function will do nothing
  325.         and return immediately.
  326.  
  327.         If  the  bar's  value  is  to  be  changed at the same time as other
  328.         properties it is better to use SetProgBarAttrs().
  329.  
  330.         This function is identical to "UpdateProgBar( PBar, 0 )".
  331.  
  332. RESULT
  333.         None
  334.  
  335. BUGS
  336.         None known
  337.  
  338. SEE ALSO
  339.         CreateProgBar() SetProgBarAttrs() FreeProgBar() RefreshProgBar()
  340.         UpdateProgBar()
  341.  
  342.  
  343.  
  344. ClearProgBar()
  345. --------------
  346.  
  347. NAME
  348.         ClearProgBar -- Removes a progress bar from the display.  (V1.00)
  349.  
  350. SYNOPSIS
  351.         ClearProgBar ( PBar )    ( A0 )
  352.  
  353.         void ClearProgBar ( PBAR * )
  354.  
  355. FUNCTION
  356.         Removes  the  supplied  progress  bar from the display.  It does not
  357.         release  the  memory  used  by the progress bar.
  358.  
  359. INPUTS
  360.         PBar - A  pointer to the progress bar whose imagery is to be erased.
  361.                This is the pointer returned by CreateProgBar().
  362.  
  363. NOTES
  364.         If  the  supplied PBAR pointer is NULL this function will do nothing
  365.         and return immediately.
  366.  
  367.         If  your  progress bar does not have any text associated with it, or
  368.         if  the text is centred within the bar, it will be marginally faster
  369.         to call ClearBar() instead.
  370.  
  371.         If you only want to delete the progress bar's text then it is better
  372.         to call ClearText().
  373.  
  374. RESULT
  375.         None
  376.  
  377. BUGS
  378.         None known
  379.  
  380. SEE ALSO
  381.         CreateProgBar() SetProgBarAttrs() FreeProgBar() ClearBar()
  382.         ClearText()
  383.  
  384.  
  385.  
  386. ClearBar()
  387. ----------
  388.  
  389. NAME
  390.         ClearBar -- Removes  a  progress  bar from the display, but does not
  391.                     remove any text.  (V1.00)
  392.  
  393. SYNOPSIS
  394.         ClearBar ( PBar )     ( A0 )
  395.  
  396.         void ClearBar ( PBAR * )
  397.  
  398. FUNCTION
  399.         Removes  the  supplied  progress  bar from the display, but does not
  400.         delete  the bar's text, if any.  It does not release the memory used
  401.         by the progress bar.
  402.  
  403. INPUTS
  404.         PBar - A  pointer to the progress bar whose imagery is to be erased.
  405.                This is the pointer returned by CreateProgBar().
  406.  
  407. NOTES
  408.         If  the  supplied PBAR pointer is NULL this function will do nothing
  409.         and return immediately.
  410.  
  411. RESULT
  412.         None
  413.  
  414. BUGS
  415.         None known
  416.  
  417. SEE ALSO
  418.         CreateProgBar() SetProgBarAttrs() FreeProgBar() ClearProgBar()
  419.         ClearText()
  420.  
  421.  
  422.  
  423. ClearText()
  424. -----------
  425.  
  426. NAME
  427.         ClearText -- Removes a progress bar's text from the display.  (V1.00)
  428.  
  429. SYNOPSIS
  430.         ClearText ( PBar )    ( A0 )
  431.  
  432.         void ClearText ( PBAR * )
  433.  
  434. FUNCTION
  435.         Removes  the supplied progress bar's text from the display.  It does
  436.         not affect the image of the bar itself.
  437.  
  438. INPUTS
  439.         PBar - A  pointer  to  the  progress bar whose text is to be erased.
  440.                This is the pointer returned by CreateProgBar().
  441.  
  442. NOTES
  443.         If  the  supplied PBAR pointer is NULL this function will do nothing
  444.         and return immediately.  Also, if the supplied progress bar does not
  445.         have  any text, or the text is centred within the bar, this function
  446.         will have no effect.
  447.  
  448. RESULT
  449.         None
  450.  
  451. BUGS
  452.         None known
  453.  
  454. SEE ALSO
  455.         CreateProgBar() SetProgBarAttrs() FreeProgBar() ClearProgBar()
  456.         ClearBar()
  457.